<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>The key Event</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>The key Event</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content"><div class="intro">
    <p>The <code>event-key</code> module adds the "key" event for subscribing to keyboard
    events triggered by users entering specific keys.  The subscription
    signature includes a filter configuration that can be used to limit event
    triggering based on key codes, shift, ctrl, alt, or meta keys pressed, as
    well as specifying the keyboard event (<code>keydown</code>, <code>keyup</code>, or
    <code>keypress</code>).</p>
</div>

<h2 id="the-filtering-spec">The filtering spec</h2>

<p>Example subscriptions might look like this:</p>

<pre class="code prettyprint">&#x2F;&#x2F; certain keys can be referenced by name
input.on(&#x27;key&#x27;, saveAndClose, &#x27;enter&#x27;);

&#x2F;&#x2F; require modifier keys with +(modifier)
Y.one(&#x27;doc&#x27;).on(&#x27;key&#x27;, composeMail, &#x27;n+ctrl&#x27;);

&#x2F;&#x2F; specify the event and key codes
datatable.get(&#x27;contentBox&#x27;)
    .delegate(&#x27;key&#x27;, moveAround, &#x27;down:37,38,39,40&#x27;, &#x27;.yui3-datatable-liner&#x27;);</pre>


<p>The third argument is the filtering spec.  Similar to using the
<code>node.delegate()</code> method, the callback is only executed if the key event
matches the filter.  The supported filter syntax is a string defined like
this:</p>

<style>
.railroad {
    margin-top: 2em;
    border-top: 2px solid #555;
    padding: 0 3em;
    text-align: center;
}

.railroad p {
    display: inline-block;
    *display: inline; zoom:1;
    veritical-align: top;
    position: relative;
    margin: 0 1.2em;
    padding: .2em;
    background: #fff;
    top: -.85em;
    font-size: 1.2em;
    font-weight: bold;
    *font-weight: normal;
}

.branch {
    position: relative;
    margin: 10px 20px 0;
    *margin-top: 0;
    border: 2px solid #555;
    border-top-width: 0;
    border-bottom-right-radius: 10px;
    border-bottom-left-radius: 10px;
    text-align: center;
    height: 1.25em;
    *height: 2em;
    line-height: 1.25em;
    *width: 7em;
}
.branch:before {
    display: block;
    position: absolute;
    left: -12px;
    top: -12px;
    content: ' ';
    height: 10px;
    width: 10px;
    border-top-right-radius: 10px;
    border: 2px solid #555;
    border-width: 2px 2px 0 0;
}
.branch:after {
    display: block;
    position: absolute;
    right: -12px;
    top: -12px;
    content: ' ';
    height: 10px;
    width: 10px;
    border-top-left-radius: 10px;
    border: 2px solid #555;
    border-width: 2px 0 0 2px;
}
.branch p {
    top: 0;
    *top: .8em;
    _top: 1em;
    line-height: 1.6em;
    z-index: 5;
}

.loop {
    position: relative;
    top: -2px;
    border: 2px solid #555;
    *border-top-width: 0;
    *top: 0;
    border-radius: 10px;
    text-align: center;
    height: 2.25em;
    margin: 0 20px;
    z-index: 4;
}
.loop p {
    top: .85em;
    z-index: 5;
}

.token {
    padding: .15em .4em .25em;
    color: #fff;
    text-shadow: -1px -1px 1px #471F1F;
    border-radius: .5em;

    background-color: #733;
    background-image: -webkit-linear-gradient(top, #a55, #733); 
    background-image:    -moz-linear-gradient(top, #a55, #733); 
    background-image:     -ms-linear-gradient(top, #a55, #733); 
    background-image:      -o-linear-gradient(top, #a55, #733); 
    background-image:         linear-gradient(top, #a55, #733);
    filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#aa5555', EndColorStr='#773333'); 
}

#code-branch .branch, #code-branch .loop {
    width: 7em;
}
#mod-branch .branch, #mod-branch .loop {
    width: 10.5em;
}
</style>


<ol>
    <li>(0..1) <span class="token">type</span> followed by a colon</li>
    <li>(0..n) comma separated <span class="token">code</span>s</li>
    <li>(0..n) <span class="token">modifier</span>s, each preceded by "+"</li>
</ol>

<h4 id="choo-choo">Choo choo!</h4>
<p>If you're into railroad diagrams, the filter spec looks like this:</p>

<ul class="railroad yui3-g">
    <li class="yui3-u">
        <p>"</p>
    </li>
    <li class="yui3-u">
        <div class="branch">
            <p><span class="token">type</span> :</p>
        </div>
    </li>
    <li class="yui3-u" id="code-branch">
        <div class="branch">
            <p><span class="token">code</span></p>
        </div>
        <div class="loop">
            <p>,</p>
        </div>
    </li>
    <li class="yui3-u" id="mod-branch">
        <div class="branch">
            <p>+<span class="token">modifier</span></p>
        </div>
        <div class="loop"></div>
    </li>
    <li class="yui3-u">
        <p>"</p>
    </li>
</ul>

<h4 id="filter-tokens">Filter tokens</h4>

<dl>
    <dt><span class="token">type</span></dt>
        <dd>"down", "up", or "press" for <code>keydown</code>, <code>keyup</code>, and <code>keypress</code>.
        The default is <code>keypress</code>.</dd>

    <dt><span class="token">code</span><dt>
        <dd>Any numeric <code>keyCode</code>, unicode character, or <a
        href="#common">common key name</a>.</dd>

    <dt><span class="token">modifier</span></dt>
        <dd>"shift", "alt", "ctrl", or "meta". "meta" is the Windows key on
        Windows-friendly keyboards or the Command key on Apple keyboards.
        Remember each must be prefixed with "+".</dd>
</dl>

<h2 id="common">Common keys by name</h2>

<p>Certain keys are common enough that referring to them by name is just easier
and makes the code more readable.  The supported key names are:</p>

<table>
<thead>
    <tr>
        <th>Name</th>
        <th><code>e.keyCode</code></th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>enter</td>
        <td>13</td>
    </tr>
    <tr>
        <td>esc</td>
        <td>27</td>
    </tr>
    <tr>
        <td>backspace</td>
        <td>8</td>
    </tr>
    <tr>
        <td>tab</td>
        <td>9</td>
    </tr>
    <tr>
        <td>pageup</td>
        <td>33</td>
    </tr>
    <tr>
        <td>pagedown</td>
        <td>34</td>
    </tr>
</tbody>
</table>

<p>If any of these are found in the spec, the default <span
class="token">type</span> becomes <code>keydown</code>.</p>

<p>If you have a mind to extend this map, it's stored in
<code>Y.Node.DOM_EVENTS.key.eventDef.KEY_MAP</code>.  For example, to add support for
<code>node.on(&#x27;key&#x27;, callback, &#x27;arrowup&#x27;)</code>, you'd do:</p>

<pre class="code prettyprint">Y.Node.DOM_EVENTS.key.eventDef.KEY_MAP.arrowup = 38;</pre>


<h2 id="caveats">Caveats</h2>

<ol>
    <li>
        You can't yet indicate that <span class="token">modifier</span>s must
        <em>not</em> be in effect or key combinations must <em>only</em>
        include those <span class="token">modifier</span>s.
    </li>
    <li>
        You can't yet specify <span class="token">type</span>s or <span
        class="token">modifier</span>s on a per-<span class="token">code</span>
        basis.
    </li>
    <li>
        Though you can specify keys by their common name, the event is not yet
        decorated in any way with that common name, so you still have to refer
        to the <code>keyCode</code> in callback code.
    </li>
</ol>
</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#the-filtering-spec">The filtering spec</a>
<ul class="toc">
<li>
<a href="#choo-choo">Choo choo!</a>
</li>
<li>
<a href="#filter-tokens">Filter tokens</a>
</li>
</ul>
</li>
<li>
<a href="#common">Common keys by name</a>
</li>
<li>
<a href="#caveats">Caveats</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="Use the Event Utility to attach simple DOM event handlers.">
                                        <a href="basic-example.html">Simple DOM Events</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Using the synthetic event API to create a DOM event that fires in response to arrow keys being pressed.">
                                        <a href="synth-example.html">Creating an Arrow Event for DOM Subscription</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Supporting cross-device swipe gestures, using the event-move gesture events">
                                        <a href="swipe-example.html">Supporting A Swipe Left Gesture</a>
                                    </li>
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                        </ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples That Use This Component</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                            
                                
                            
                                
                            
                                
                                    <li data-description="Shows how to extend the base widget class, to create your own Widgets.">
                                        <a href="../widget/widget-extend.html">Extending the Base Widget Class</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Creating an accessible menu button using the Focus Manager Node Plugin, Event&#x27;s delegation support and mouseenter event, along with the Overlay widget and Node&#x27;s support for the WAI-ARIA Roles and States.">
                                        <a href="../node-focusmanager/node-focusmanager-3.html">Accessible Menu Button</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Use IO to request data over HTTP.">
                                        <a href="../io/get.html">HTTP GET to request data</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Example Photo Browser application.">
                                        <a href="../dd/photo-browser.html">Photo Browser</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Portal style example using Drag &amp; Drop Event Bubbling and Animation.">
                                        <a href="../dd/portal-drag.html">Portal Style Example</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
